<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Dom_Query - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.dom.query.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.dom.query.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dom.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dom.html">Zend_Dom</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.exception.html">Zend_Exception</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.dom.query" class="section"><div class="info"><h1 class="title">Zend_Dom_Query</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Dom_Query</span> provides mechanisms for querying
        <acronym class="acronym">XML</acronym> and (X)<acronym class="acronym">HTML</acronym> documents utilizing either XPath or
        <acronym class="acronym">CSS</acronym> selectors. It was developed to aid with functional testing of
        <acronym class="acronym">MVC</acronym> applications, but could also be used for rapid development of screen
        scrapers.
    </p>

    <p class="para">
        <acronym class="acronym">CSS</acronym> selector notation is provided as a simpler and more familiar
        notation for web developers to utilize when querying documents with <acronym class="acronym">XML</acronym>
        structures. The notation should be familiar to anybody who has developed
        Cascading Style Sheets or who utilizes Javascript toolkits that provide
        functionality for selecting nodes utilizing <acronym class="acronym">CSS</acronym> selectors
        (<a href="http://prototypejs.org/api/utility/dollar-dollar" class="link external">&raquo; Prototype&#039;s
            $$()</a> and
        <a href="http://api.dojotoolkit.org/jsdoc/dojo/HEAD/dojo.query" class="link external">&raquo; Dojo&#039;s
            dojo.query</a> were both inspirations for the component).
    </p>

    <div class="section" id="zend.dom.query.operation"><div class="info"><h1 class="title">Theory of Operation</h1></div>
        

        <p class="para">
            To use <span class="classname">Zend_Dom_Query</span>, you instantiate a
            <span class="classname">Zend_Dom_Query</span> object, optionally passing a document to
            query (a string). Once you have a document, you can use either the
             <span class="methodname">query()</span> or  <span class="methodname">queryXpath()</span> methods; each
            method will return a <span class="classname">Zend_Dom_Query_Result</span> object with
            any matching nodes.
        </p>

        <p class="para">
            The primary difference between <span class="classname">Zend_Dom_Query</span> and using
            DOMDocument + DOMXPath is the ability to select against <acronym class="acronym">CSS</acronym>
            selectors. You can utilize any of the following, in any combination:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    <em class="emphasis">element types</em>: provide an element type to
                    match: &#039;div&#039;, &#039;a&#039;, &#039;span&#039;, &#039;h2&#039;, etc.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">style attributes</em>: <acronym class="acronym">CSS</acronym> style attributes
                    to match: &#039;<strong class="command">.error</strong>&#039;, &#039;<strong class="command">div.error</strong>&#039;,
                    &#039;<strong class="command">label.required</strong>&#039;, etc. If an
                    element defines more than one style, this will match as long as
                    the named style is present anywhere in the style declaration.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">id attributes</em>: element ID attributes to
                    match: &#039;#content&#039;, &#039;div#nav&#039;, etc.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">arbitrary attributes</em>: arbitrary element
                    attributes to match. Three different types of matching are
                    provided:
                </p>

                <ul class="itemizedlist">
                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">exact match</em>: the attribute exactly
                            matches the string: &#039;div[bar=&quot;baz&quot;]&#039; would match a div
                            element with a &quot;bar&quot; attribute that exactly matches the
                            value &quot;baz&quot;.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">word match</em>: the attribute contains
                            a word matching the string: &#039;div[bar~=&quot;baz&quot;]&#039; would match a div
                            element with a &quot;bar&quot; attribute that contains the
                            word &quot;baz&quot;. &#039;&lt;div bar=&quot;foo baz&quot;&gt;&#039; would match, but &#039;&lt;div
                            bar=&quot;foo bazbat&quot;&gt;&#039; would not.
                        </p>
                    </li>

                    <li class="listitem">
                        <p class="para">
                            <em class="emphasis">substring match</em>: the attribute contains
                            the string: &#039;div[bar*=&quot;baz&quot;]&#039; would match a div
                            element with a &quot;bar&quot; attribute that contains the
                            string &quot;baz&quot; anywhere within it.
                        </p>
                    </li>
                </ul>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">direct descendents</em>: utilize &#039;&gt;&#039; between
                    selectors to denote direct descendents. &#039;div &gt; span&#039; would
                    select only &#039;span&#039; elements that are direct descendents of a
                    &#039;div&#039;. Can also be used with any of the selectors above.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    <em class="emphasis">descendents</em>: string together
                    multiple selectors to indicate a hierarchy along which
                    to search. &#039;<strong class="command">div .foo span #one</strong>&#039; would select an element
                    of id &#039;one&#039; that is a descendent of arbitrary depth
                    beneath a &#039;span&#039; element, which is in turn a descendent
                    of arbitrary depth beneath an element with a class of
                    &#039;foo&#039;, that is an descendent of arbitrary depth beneath
                    a &#039;div&#039; element. For example, it would match the link to
                    the word &#039;One&#039; in the listing below:
                </p>

                <pre class="programlisting brush: html">
&lt;div&gt;
&lt;table&gt;
    &lt;tr&gt;
        &lt;td class=&quot;foo&quot;&gt;
            &lt;div&gt;
                Lorem ipsum &lt;span class=&quot;bar&quot;&gt;
                    &lt;a href=&quot;/foo/bar&quot; id=&quot;one&quot;&gt;One&lt;/a&gt;
                    &lt;a href=&quot;/foo/baz&quot; id=&quot;two&quot;&gt;Two&lt;/a&gt;
                    &lt;a href=&quot;/foo/bat&quot; id=&quot;three&quot;&gt;Three&lt;/a&gt;
                    &lt;a href=&quot;/foo/bla&quot; id=&quot;four&quot;&gt;Four&lt;/a&gt;
                &lt;/span&gt;
            &lt;/div&gt;
        &lt;/td&gt;
    &lt;/tr&gt;
&lt;/table&gt;
&lt;/div&gt;
</pre>

            </li>
        </ul>

        <p class="para">
            Once you&#039;ve performed your query, you can then work with the result
            object to determine information about the nodes, as well as to pull
            them and/or their content directly for examination and manipulation.
            <span class="classname">Zend_Dom_Query_Result</span> implements <span class="classname">Countable</span>
            and <span class="classname">Iterator</span>, and store the results internally as
            DOMNodes and DOMElements. As an example, consider the following call,
            that selects against the <acronym class="acronym">HTML</acronym> above:
        </p>

        <pre class="programlisting brush: php">
$dom = new Zend_Dom_Query($html);
$results = $dom-&gt;query(&#039;.foo .bar a&#039;);

$count = count($results); // get number of matches: 4
foreach ($results as $result) {
    // $result is a DOMElement
}
</pre>


        <p class="para">
            <span class="classname">Zend_Dom_Query</span> also allows straight XPath queries
            utilizing the  <span class="methodname">queryXpath()</span> method; you can pass any
            valid XPath query to this method, and it will return a
            <span class="classname">Zend_Dom_Query_Result</span> object.
        </p>
    </div>

    <div class="section" id="zend.dom.query.methods"><div class="info"><h1 class="title">Methods Available</h1></div>
        

        <p class="para">
            The <span class="classname">Zend_Dom_Query</span> family of classes have the following
            methods available.
        </p>

        <div class="section" id="zend.dom.query.methods.zenddomquery"><div class="info"><h1 class="title">Zend_Dom_Query</h1></div>
            

            <p class="para">
                The following methods are available to
                <span class="classname">Zend_Dom_Query</span>:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setDocumentXml($document)</span>: specify an
                        <acronym class="acronym">XML</acronym> string to query against.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setDocumentXhtml($document)</span>: specify an
                        <acronym class="acronym">XHTML</acronym> string to query against.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setDocumentHtml($document)</span>: specify an
                        <acronym class="acronym">HTML</acronym> string to query against.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">setDocument($document)</span>: specify a
                        string to query against; <span class="classname">Zend_Dom_Query</span> will
                        then attempt to autodetect the document type.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getDocument()</span>: retrieve the original document
                        string provided to the object.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getDocumentType()</span>: retrieve the document
                        type of the document provided to the object; will be one of
                        the <b><tt>DOC_XML</tt></b>, <b><tt>DOC_XHTML</tt></b>, or
                        <b><tt>DOC_HTML</tt></b> class constants.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">query($query)</span>: query the document using
                        <acronym class="acronym">CSS</acronym> selector notation.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">queryXpath($xPathQuery)</span>: query the document
                        using XPath notation.
                    </p>
                </li>
            </ul>
        </div>

        <div class="section" id="zend.dom.query.methods.zenddomqueryresult"><div class="info"><h1 class="title">Zend_Dom_Query_Result</h1></div>
            

            <p class="para">
                As mentioned previously, <span class="classname">Zend_Dom_Query_Result</span>
                implements both <span class="classname">Iterator</span> and
                <span class="classname">Countable</span>, and as such can be used in a
                 <span class="methodname">foreach()</span> loop as well as with the
                 <span class="methodname">count()</span> function. Additionally, it exposes the
                following methods:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getCssQuery()</span>: return the <acronym class="acronym">CSS</acronym>
                        selector query used to produce the result (if any).
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getXpathQuery()</span>: return the XPath query
                        used to produce the result. Internally,
                        <span class="classname">Zend_Dom_Query</span> converts <acronym class="acronym">CSS</acronym>
                        selector queries to XPath, so this value will always be populated.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                         <span class="methodname">getDocument()</span>: retrieve the DOMDocument the
                        selection was made against.
                    </p>
                </li>
            </ul>
        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dom.introduction.html">Introduction</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dom.html">Zend_Dom</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.exception.html">Zend_Exception</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.dom.html">Zend_Dom</a></li>
  <li><a href="zend.dom.introduction.html">Introduction</a></li>
  <li class="active"><a href="zend.dom.query.html">Zend_Dom_Query</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>